fixed wording and typos in some places. added a new section "Optimizing RC

Tue Sep 13 14:16:27 2005  Tim Janik  <timj@imendio.com>

        * gtk/tmpl/gtkrc.sgml: fixed wording and typos in some places.
        added a new section "Optimizing RC Style Matches".

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 7889b1a5303d2ff063da925b98e89f774c1d6d07..3074c45f27d3229bcd4fdbdd1200e2cf4b64bb07 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+Tue Sep 13 14:16:27 2005  Tim Janik  <timj@imendio.com>
+
+       * gtk/tmpl/gtkrc.sgml: fixed wording and typos in some places.
+       added a new section "Optimizing RC Style Matches".
+
 2005-09-11  Matthias Clasen  <mclasen@redhat.com>
 
        * gdk/gdk-sections.txt: Add gdk_intern_static_string.

diff --git a/docs/reference/gdk/tmpl/gdkscreen.sgml b/docs/reference/gdk/tmpl/gdkscreen.sgml
index ea7050d4da2f8ce393725364f95b96ba8d240187..800a9e0d5594c182956fe133b54e73310b680931 100644 (file)
--- a/docs/reference/gdk/tmpl/gdkscreen.sgml
+++ b/docs/reference/gdk/tmpl/gdkscreen.sgml
@@ -41,6 +41,16 @@ when GDK gets multihead support.
 
 @gdkscreen: the object which received the signal.
 
+<!-- ##### ARG GdkScreen:font-options ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkScreen:resolution ##### -->
+<para>
+
+</para>
+
 <!-- ##### FUNCTION gdk_screen_get_default ##### -->
 <para>
 
@@ -275,6 +285,42 @@ when GDK gets multihead support.
 @Returns: 
 
 
+<!-- ##### FUNCTION gdk_screen_get_font_options ##### -->
+<para>
+
+</para>
+
+@screen: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_screen_set_font_options ##### -->
+<para>
+
+</para>
+
+@screen: 
+@options: 
+
+
+<!-- ##### FUNCTION gdk_screen_get_resolution ##### -->
+<para>
+
+</para>
+
+@screen: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_screen_set_resolution ##### -->
+<para>
+
+</para>
+
+@screen: 
+@dpi: 
+
+
 <!-- ##### FUNCTION gdk_spawn_on_screen ##### -->
 <para>
 

diff --git a/docs/reference/gdk/tmpl/properties.sgml b/docs/reference/gdk/tmpl/properties.sgml
index dc63c5ac59accad2d3996ff4405f041748afc4f8..39e40ef9130ef585ef969de81f24e7491360f621 100644 (file)
--- a/docs/reference/gdk/tmpl/properties.sgml
+++ b/docs/reference/gdk/tmpl/properties.sgml
@@ -235,6 +235,15 @@ Finds or creates an atom corresponding to a given string.
 @Returns: the atom corresponding to @atom_name.
 
 
+<!-- ##### FUNCTION gdk_atom_intern_static_string ##### -->
+<para>
+
+</para>
+
+@atom_name: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gdk_atom_name ##### -->
 <para>
 Determines the string corresponding to an atom.

diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml
index 773c6a2a8583737e6c855497f81610363760b37b..7f8687db463c17a3216fe53cbbcae2c2b56d057b 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkrc.sgml
+++ b/docs/reference/gtk/tmpl/gtkrc.sgml
@@ -51,14 +51,18 @@ attaches them to particular widgets. The attachment is done
 by the <literal>widget</literal>, <literal>widget_class</literal>,
 and <literal>class</literal> declarations. As an example
 of such a statement:
+
 <informalexample><programlisting>
 widget "mywindow.*.GtkEntry" style "my-entry-class"
 </programlisting></informalexample>
+
 attaches the style <literal>"my-entry-class"</literal>
-to all widgets whose <firstterm>widget class</firstterm>
+to all widgets whose <firstterm>widget path</firstterm>
 matches the <firstterm>pattern</firstterm>
-<literal>"mywindow.*.GtkEntry"</literal>.
+<literal>"mywindow.*.GtkEntry"</literal>. That is, all
+#GtkEntry widgets which are part of a #GtkWindow named <literal>"mywindow"</literal>.
 </para>
+
 <para>
 The patterns here are given in the standard shell glob
 syntax. The <literal>"?"</literal> wildcard matches
@@ -66,7 +70,7 @@ any character, while <literal>"*"</literal> matches
 zero or more of any character. The three types of
 matching are against the widget path, the
 <firstterm>class path</firstterm> and the class
-hierarchy. Both the widget and the class paths consists of a
+hierarchy. Both the widget path and the class path consist of a
 <literal>"."</literal> separated list of all the
 parents of the widget and the widget itself from
 outermost to innermost. The difference is that in
@@ -77,9 +81,9 @@ for the class path, the class name is always used.
 </para>
 <para>
 So, if you have a #GtkEntry named
-<literal>"myentry"</literal>, inside of a of a window
+<literal>"myentry"</literal>, inside of a horizontal box in a window
 named <literal>"mywindow"</literal>, then the
-widget path is: <literal>"mwindow.GtkHBox.myentry"</literal>
+widget path is: <literal>"mywindow.GtkHBox.myentry"</literal>
 while the class path is: <literal>"GtkWindow.GtkHBox.GtkEntry"</literal>.
 </para>
 <para>
@@ -119,6 +123,80 @@ that GTK+ creates internally.
 
 </refsect2>
 
+<refsect2><title>Optimizing RC Style Matches</title>
+<para>
+Everytime a widget is created and added to the layout hierarchy of a #GtkWindow
+("anchored" to be exact), a list of matching RC styles out of all RC styles read
+in so far is composed.
+For this, every RC style is matched against the widgets class path,
+the widgets name path and widgets inheritance hierarchy.
+As a consequence, significant slowdown can be caused by utilization of many
+RC styles and by using RC sytle patterns that are slow or complicated to match
+against a given widget.
+The following ordered list provides a number of advices (prioritized by effectiveness)
+to reduce the performance overhead associated with RC style matches:
+
+<orderedlist>
+
+  <listitem><para>
+  Move RC styles for specific applications into RC files dedicated to those
+  applications and parse application specific RC files only from
+  applications that are affected by them.
+  This reduces the overall amount of RC styles that have to be considered
+  for a match across a group of applications.
+  </para></listitem>
+
+  <listitem><para>
+  Merge multiple styles which use the same matching rule, for instance:
+<informalexample><programlisting>
+     style "Foo" { foo_content }
+     class "X" style "Foo"
+     style "Bar" { bar_content }
+     class "X" style "Bar"
+</programlisting></informalexample>
+   is faster to match as:
+<informalexample><programlisting>
+     style "FooBar" { foo_content bar_content }
+     class "X" style "FooBar"
+</programlisting></informalexample>
+  </para></listitem>
+
+  <listitem><para>
+  Use of wildcards should be avoided, this can reduce the individual RC style
+  match to a single integer comparison in most cases.
+  </para></listitem>
+
+  <listitem><para>
+  To avoid complex recursive matching, specification of full class names
+  (for <literal>class</literal> matches) or full path names (for
+  <literal>widget</literal> and <literal>widget_class</literal> matches)
+  is to be preferred over shortened names
+  containing <literal>"*"</literal> or <literal>"?"</literal>.
+  </para></listitem>
+
+  <listitem><para>
+  If at all necessary, wildcards should only be used at the tail or head
+  of a pattern. This reduces the match complexity to a string comparison
+  per RC style.
+  </para></listitem>
+
+  <listitem><para>
+  When using wildcards, use of <literal>"?"</literal> should be preferred
+  over <literal>"*"</literal>. This can reduce the matching complexity from
+  O(n^2) to O(n). For example <literal>"Gtk*Box"</literal> can be turned into
+  <literal>"Gtk?Box"</literal> and will still match #GtkHBox and #GtkVBox.
+  </para></listitem>
+
+  <listitem><para>
+  The use of <literal>"*"</literal> wildcards should be restricted as much
+  as possible, because matching <literal>"A*B*C*RestString"</literal> can
+  result in matching complexities worse than O(n^2) in the length of strings.
+  </para></listitem>
+</orderedlist>
+
+</para>
+</refsect2>
+
 <refsect2><title>Toplevel declarations</title>
 <para>
 An RC file is a text file which is composed of a sequence

diff --git a/docs/reference/gtk/tmpl/gtkselection.sgml b/docs/reference/gtk/tmpl/gtkselection.sgml
index 7728143b84ca07206eac2caeba26b970e970062e..e272972cf95c695e66c66aecb804a6c71d2a861a 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkselection.sgml
+++ b/docs/reference/gtk/tmpl/gtkselection.sgml
@@ -332,6 +332,46 @@ selection handling code.
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_selection_data_targets_include_uri ##### -->
+<para>
+
+</para>
+
+@selection_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_targets_include_image ##### -->
+<para>
+
+</para>
+
+@targets: 
+@n_targets: 
+@writable: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_targets_include_text ##### -->
+<para>
+
+</para>
+
+@targets: 
+@n_targets: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_targets_include_uri ##### -->
+<para>
+
+</para>
+
+@targets: 
+@n_targets: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_selection_remove_all ##### -->
 <para>
 </para>

diff --git a/docs/reference/gtk/tmpl/gtkstock.sgml b/docs/reference/gtk/tmpl/gtkstock.sgml
index 369dd8e33b5dd0dc391052b8c434b49cccc83a7f..4b8c91540326d702bf426623d300ce04a4d543ea 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkstock.sgml
+++ b/docs/reference/gtk/tmpl/gtkstock.sgml
@@ -773,6 +773,7 @@ The "Save As" item.
 </para>
 
 
+
 <!-- ##### MACRO GTK_STOCK_SELECT_ALL ##### -->
 <para>
 The "Select All" item.
@@ -781,6 +782,7 @@ The "Select All" item.
 
 @Since: 2.10
 
+
 <!-- ##### MACRO GTK_STOCK_SELECT_COLOR ##### -->
 <para>
 The "Color" item.

diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml
index 57faf2d14632da8b2241a6a12abd61d66f08f6ed..3d07d9a538e382ff7f9200a2483e263978ebffd2 100644 (file)
--- a/docs/reference/gtk/tmpl/gtktoolbar.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml
@@ -102,6 +102,16 @@ accessed through the function described below.
 @toolbar: 
 @style: 
 
+<!-- ##### ARG GtkToolbar:icon-size ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkToolbar:icon-size-set ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkToolbar:orientation ##### -->
 <para>
 

diff --git a/docs/reference/gtk/tmpl/gtkwindow.sgml b/docs/reference/gtk/tmpl/gtkwindow.sgml
index dfb1a77903c34e02c07ad5ba1c12ca1765eec01a..1cd7a2ba98e1eb8d45836b65db21c12846579648 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkwindow.sgml
+++ b/docs/reference/gtk/tmpl/gtkwindow.sgml
@@ -99,6 +99,11 @@ Toplevel which can contain other widgets
 
 </para>
 
+<!-- ##### ARG GtkWindow:deletable ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkWindow:destroy-with-parent ##### -->
 <para>
 
@@ -688,6 +693,15 @@ Deprecated alias for gtk_window_set_position().
 @setting: 
 
 
+<!-- ##### FUNCTION gtk_window_set_deletable ##### -->
+<para>
+
+</para>
+
+@window: 
+@setting: 
+
+
 <!-- ##### FUNCTION gtk_window_set_frame_dimensions ##### -->
 <para>
 
@@ -790,6 +804,15 @@ Deprecated alias for gtk_window_set_position().
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_window_get_deletable ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_window_get_default_icon_list ##### -->
 <para>